{
 "cells": [
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "---\n",
    "title: Intro to value ownership\n",
    "order: 1\n",
    "sidebar_position: 1\n",
    "description: Introduction to Mojo value ownership.\n",
    "css: /static/styles/page-navigation.css\n",
    "website:\n",
    "  open-graph:\n",
    "    image: /static/images/mojo-social-card.png\n",
    "  twitter-card:\n",
    "    image: /static/images/mojo-social-card.png\n",
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A program is nothing without data, and all modern programming languages store\n",
    "data in one of two places: the call stack and the heap (also sometimes in CPU\n",
    "registers, but we won't get into that here). However, each language reads and\n",
    "writes data a bit differently—sometimes very differently. So in the following\n",
    "sections, we'll explain how Mojo manages memory in your programs and how this\n",
    "affects the way you write Mojo code."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Stack and heap overview\n",
    "\n",
    "In general, all programming languages use a call stack the same way: When a\n",
    "function is called, the compiler allocates a block of memory on the stack that\n",
    "is exactly the size required to store the execution logic and _fixed-size_\n",
    "local values. When another function is called, its data is likewise added to\n",
    "the top of the stack. When a function is done, all its data in the stack is\n",
    "destroyed so that memory becomes available for other code.\n",
    "\n",
    "Notice that we said only \"_fixed-size_ local values\" are stored in the stack.\n",
    "Dynamically-sized values that can change in size at runtime are instead\n",
    "stored in the heap, which is a much larger region of memory that allows for\n",
    "dynamic memory access at runtime. Technically, a local variable for such a value\n",
    "is still stored in the call stack, but its value is a fixed-size pointer to the\n",
    "real value on the heap.\n",
    "\n",
    "Additionally, values that need to outlive the lifetime of a function (such as\n",
    "an array that's passed between functions and should not be copied) are stored\n",
    "in the heap, because heap memory is accessible from anywhere in the call stack,\n",
    "even after the function that created it is removed from the stack. This sort of\n",
    "situation—in which a heap-allocated value is used by multiple functions—is where\n",
    "most memory errors occur, and it's where memory management strategies vary the\n",
    "most between programming languages."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Memory management strategies\n",
    "\n",
    "Because memory is limited, it's important that programs remove unused data from\n",
    "the heap (\"free\" the memory) as quickly as possible. Figuring out when to free\n",
    "that memory is pretty complicated.\n",
    "\n",
    "Some programming languages try to hide the complexities of memory management\n",
    "from you by utilizing a \"garbage collector\" process that tracks all memory\n",
    "usage and deallocates unused heap memory periodically (also known as automatic\n",
    "memory management). A significant benefit of this method is that it relieves\n",
    "developers from the burden of manual memory management, generally avoiding more\n",
    "errors and making developers more productive. However, it incurs a performance\n",
    "cost because the garbage collector interrupts the program's execution, and it\n",
    "might not reclaim memory very quickly.\n",
    "\n",
    "Other languages require that you manually free data that's allocated on the\n",
    "heap. When done properly, this makes programs execute quickly, because there's\n",
    "no processing time consumed by a garbage collector. However, the challenge with\n",
    "this approach is that programmers make mistakes, especially when multiple parts\n",
    "of the program need access to the same memory—it becomes difficult to know\n",
    "which part of the program \"owns\" the data and must deallocate it. Programmers\n",
    "might accidentally deallocate data before the program is done with it (causing\n",
    "\"use-after-free\" errors), or they might deallocate it twice (\"double free\"\n",
    "errors), or they might never deallocate it (\"leaked memory\" errors). Mistakes\n",
    "like these and others can have catastrophic results for the program, and these\n",
    "bugs are often hard to track down, making it especially important that they\n",
    "don't occur in the first place.\n",
    "\n",
    "Mojo uses a third approach called \"ownership\" that relies on a collection of\n",
    "rules that programmers must follow when passing values. The rules ensure there\n",
    "is only one \"owner\" for each chunk of memory at a time, and that the memory is\n",
    "deallocated accordingly. In this way, Mojo automatically allocates and\n",
    "deallocates heap memory for you, but it does so in a way that's deterministic\n",
    "and safe from errors such as use-after-free, double-free and memory leaks. Plus,\n",
    "it does so with a very low performance overhead.\n",
    "\n",
    "Mojo's value ownership model provides an excellent balance of programming\n",
    "productivity and strong memory safety. It only requires that you learn some new\n",
    "syntax and a few rules about how to share access to memory within your program.\n",
    "\n",
    "But before we explain the rules and syntax for Mojo's value ownership model,\n",
    "you first need to understand [value\n",
    "semantics](/mojo/manual/values/value-semantics.html)."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Mojo",
   "language": "mojo",
   "name": "mojo-jupyter-kernel"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "mojo"
   },
   "file_extension": ".mojo",
   "mimetype": "text/x-mojo",
   "name": "mojo"
  },
  "orig_nbformat": 4
 },
 "nbformat": 4,
 "nbformat_minor": 2
}
